<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SoundSet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>SoundSet</h1>

<p>Changes various settings of a sound device (master mute, master volume, etc.)</p>

<pre class="Syntax">SoundSet, NewSetting [, ComponentType, ControlType, DeviceNumber]</pre>
<h3>Parameters</h3>
<dl>

  <dt>NewSetting</dt>
  <dd><p>Percentage number between -100 and 100 inclusive (it can be a floating point number or <a href="../Variables.htm#Expressions">expression</a>). If the number begins with a plus or minus sign, the <strong>current setting</strong> will be adjusted up or down by the indicated amount. Otherwise, the setting will be set explicitly to the level indicated by <em>NewSetting</em>.</p>
      <p>For <em>ControlTypes</em> with only two possible settings -- namely ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, and BASSBOOST -- any positive number will turn on the setting and a zero will turn it off. However, if the number begins with a plus or minus sign, the  setting  will be toggled (set to the opposite of its current state).</p></dd>

  <dt>ComponentType</dt>
  <dd><p>If omitted or blank, it defaults to the word MASTER. Otherwise, it can be one of the following words: MASTER (synonymous with SPEAKERS), DIGITAL, LINE, MICROPHONE, SYNTH, CD, TELEPHONE, PCSPEAKER, WAVE, AUX, ANALOG, HEADPHONES, or N/A. If the sound device lacks the specified <em>ComponentType</em>, ErrorLevel will indicate the problem.</p>
      <p>The component labeled Auxiliary in some mixers might be accessible as ANALOG rather than AUX.</p>
    <p>If a device has more than one instance of <em>ComponentType</em> (two of type LINE, for example), usually the first contains the playback settings and the second contains the recording settings. To access an instance other than the first, append a colon and a number to this parameter. For example: <code>Analog:2</code> is the second instance of the analog component.</p></dd>

  <dt>ControlType</dt>
  <dd><p>If omitted or blank, it defaults to VOLUME. Otherwise, it can be one of the following words: VOLUME (or VOL), ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, BASSBOOST, PAN, QSOUNDPAN, BASS, TREBLE, EQUALIZER, or the number of a valid control type (see <a href="#Ex">soundcard analysis script</a>). If the specified <em>ComponentType</em> lacks the specified <em>ControlType</em>, ErrorLevel will indicate the problem.</p>
    <p><strong>Note:</strong> sound devices usually support only VOLUME (or VOL) and MUTE, although others may be available depending on Windows and the sound device.</p></dd>

  <dt>DeviceNumber</dt>
  <dd><p>A number between 1 and the total number of supported devices. If this parameter is omitted, it defaults to 1 (the first sound device), or on Windows Vista or above, the system's default device for playback. This parameter can be an <a href="../Variables.htm#Expressions">expression</a>. The <a href="#Ex">soundcard analysis script</a> may help determine which number to use.</p></dd>

</dl>
<h3>ErrorLevel</h3>
<p><span class="ver">[v1.1.04+]</span> This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0 if the command succeeded. Otherwise, it is set to one of the following phrases:</p>
<table class="info" style="width:436px">
  <tr>
    <td width="426">Invalid Control Type or Component Type</td>
  </tr>
  <tr>
    <td>Can't Open Specified Mixer</td>
  </tr>
  <tr>
    <td>Mixer Doesn't Support This Component Type</td>
  </tr>
  <tr>
    <td>Mixer Doesn't Have That Many of That Component Type</td>
  </tr>
  <tr>
    <td>Component Doesn't Support This Control Type</td>
  </tr>
  <tr>
    <td>Can't Get Current Setting</td>
  </tr>
  <tr>
    <td>Can't Change Setting</td>
  </tr>
</table>
<h3>Remarks</h3>
<p>Support for Windows Vista and later was added in v1.1.10.</p>
<p>For more functionality and finer grained control over audio, consider using the <a href="http://www.autohotkey.com/board/topic/21984-vista-audio-control-functions/">VA library</a>.</p>
<p>An alternative way to adjust the volume is to have the script send volume-control keystrokes to change the master volume for the entire system, such as in the example below:</p>
<pre>Send {Volume_Up}  <em>; Raise the master volume by 1 interval (typically 5%).</em>
Send {Volume_Down 3}  <em>; Lower the master volume by 3 intervals.</em>
Send {Volume_Mute}  <em>; Mute/unmute the master volume.</em></pre>
<p>To discover the capabilities of the sound devices (mixers) installed on the system -- such as the available component types and control types -- run the <a href="#Ex">soundcard analysis script</a>.</p>
<p>Windows 2000/XP/2003: When SoundSet changes the volume of a component, all of that component's channels (e.g. left and right) are set to the same level. In other words, any off-center &quot;balance&quot; that may have been set previously is lost. This can be avoided for the WAVE component by using <a href="SoundSetWaveVolume.htm">SoundSetWaveVolume</a> instead, which attempts to preserve the existing balance when changing the volume level.</p>
<p>Windows Vista and later (v1.1.10+): SoundSet attempts to preserve the existing balance when changing the volume level.</p>
<p>Use <a href="SoundGet.htm">SoundGet</a> to retrieve the current value of a setting.</p>
<h3>Related</h3>
<p><a href="SoundGet.htm">SoundGet</a>, <a href="SoundGetWaveVolume.htm">SoundGetWaveVolume</a>, <a href="SoundSetWaveVolume.htm">SoundSetWaveVolume</a>, <a href="SoundPlay.htm">SoundPlay</a></p>
<h3>Examples</h3>
<pre class="NoIndent"><em>; BASIC EXAMPLES:</em>
SoundSet, 50  <em>; Set the master volume to 50%</em>
SoundSet +10  <em>; Increase master volume by 10%</em>
SoundSet -10  <em>; Decrease master volume by 10%</em>
SoundSet, 1, Microphone, mute  <em>; mute the microphone</em>
SoundSet, +1, , mute  <em>; Toggle the master mute (set it to the opposite state)</em>
SoundSet, +20, Master, bass  <em>; Increase bass level by 20%.</em>
if ErrorLevel
    MsgBox, The BASS setting is not supported for MASTER.</pre>
<h4 id="Ex">Soundcard Analysis</h4>
<p>Use the following script to discover your soundcard's capabilities (component types and control types). It displays the results in a simple ListView. Alternatively, a script for Windows Vista and later which provides more detail (such as display names of devices) can be downloaded from the following forum topic: <a href="http://www.autohotkey.com/board/topic/90877-/">http://www.autohotkey.com/board/topic/90877-/</a></p>
<pre class="NoIndent">SetBatchLines -1
SplashTextOn,,, Gathering Soundcard Info...

<em>; Most of the pure numbers below probably don't exist in any mixer, but they're queried for completeness.
; The numbers correspond to the following items (in order): CUSTOM, BOOLEANMETER, SIGNEDMETER, PEAKMETER,
; UNSIGNEDMETER, BOOLEAN, BUTTON, DECIBELS, SIGNED, UNSIGNED, PERCENT, SLIDER, FADER, SINGLESELECT, MUX,
; MULTIPLESELECT, MIXER, MICROTIME, MILLITIME</em>
ControlTypes = VOLUME,ONOFF,MUTE,MONO,LOUDNESS,STEREOENH,BASSBOOST,PAN,QSOUNDPAN,BASS,TREBLE,EQUALIZER,0x00000000, 0x10010000,0x10020000,0x10020001,0x10030000,0x20010000,0x21010000,0x30040000,0x30020000,0x30030000,0x30050000,0x40020000,0x50030000,0x70010000,0x70010001,0x71010000,0x71010001,0x60030000,0x61030000

ComponentTypes = MASTER,HEADPHONES,DIGITAL,LINE,MICROPHONE,SYNTH,CD,TELEPHONE,PCSPEAKER,WAVE,AUX,ANALOG,N/A

<em>; Create a ListView and prepare for the main loop:</em>
Gui, Add, Listview, w400 h400 vMyListView, Component Type|Control Type|Setting|Mixer
LV_ModifyCol(4, &quot;Integer&quot;)
SetFormat, Float, 0.2  <em>; Limit number of decimal places in percentages to two.</em>

Loop  <em>; For each mixer number that exists in the system, query its capabilities.</em>
{
    CurrMixer := A_Index
    SoundGet, Setting,,, %CurrMixer%
    if ErrorLevel = Can't Open Specified Mixer  <em>; Any error other than this indicates that the mixer exists.</em>
        break

    <em>; For each component type that exists in this mixer, query its instances and control types:</em>
    Loop, parse, ComponentTypes, `,
    {
        CurrComponent := A_LoopField
        <em>; First check if this component type even exists in the mixer:</em>
        SoundGet, Setting, %CurrComponent%,, %CurrMixer%
        if ErrorLevel = Mixer Doesn't Support This Component Type
            continue  <em>; Start a new iteration to move on to the next component type.</em>
        Loop  <em>; For each instance of this component type, query its control types.</em>
        {
            CurrInstance := A_Index
            <em>; First check if this instance of this instance even exists in the mixer:</em>
            SoundGet, Setting, %CurrComponent%:%CurrInstance%,, %CurrMixer%
            <em>; Checking for both of the following errors allows this script to run on older versions:</em>
            if ErrorLevel in Mixer Doesn't Have That Many of That Component Type,Invalid Control Type or Component Type
                break  <em>; No more instances of this component type.</em>
            <em>; Get the current setting of each control type that exists in this instance of this component:</em>
            Loop, parse, ControlTypes, `,
            {
                CurrControl := A_LoopField
                SoundGet, Setting, %CurrComponent%:%CurrInstance%, %CurrControl%, %CurrMixer%
                <em>; Checking for both of the following errors allows this script to run on older versions:</em>
                if ErrorLevel in Component Doesn't Support This Control Type,Invalid Control Type or Component Type
                    continue
                if ErrorLevel  <em>; Some other error, which is unexpected so show it in the results.</em>
                    Setting := ErrorLevel
                ComponentString := CurrComponent
                if CurrInstance &gt; 1
                    ComponentString = %ComponentString%:%CurrInstance%
                LV_Add(&quot;&quot;, ComponentString, CurrControl, Setting, CurrMixer)
            }  <em>; For each control type.</em>
        }  <em>; For each component instance.</em>
    }  <em>; For each component type.</em>
}  <em>; For each mixer.</em>

Loop % LV_GetCount(&quot;Col&quot;)  <em>; Auto-size each column to fit its contents.</em>
    LV_ModifyCol(A_Index, &quot;AutoHdr&quot;)

SplashTextOff
Gui, Show
return

GuiClose:
ExitApp</pre>

</body>
</html>
